gh-146636: Add Free-threaded Stable ABI migration guide by clin1234 · Pull Request #148453 · python/cpython

clin1234 · 2026-04-12T15:07:16Z

Issue: Implement PEP 803 -- abi3t #146636

📚 Documentation preview 📚: https://cpython-previews--148453.org.readthedocs.build/

da-woods

There's a lot that isn't right here (or is mostly about freethreading generally rather than about the stable ABI).

da-woods · 2026-04-12T15:57:00Z

+:c:func:`PyDict_SetItem`, or explicitly using macros), it attempts to acquire
+the underlying mutex.
+
+Using Critical Sections


The weakness right now is that I don't think they're part of the stable ABI (but hopefully will be)

If you were referring to https://docs.python.org/3/c-api/dict.html#c.PyDict_SetItem, it's part of the Stable ABI: https://docs.python.org/3/c-api/dict.html#c.PyDict_SetItem

No - I was referring to critical sections. Which I really hope are added before 3.15 comes out but I don't think currently are. Sorry if that was ambiguous.

Now being proposed: #149225

da-woods · 2026-04-12T16:14:50Z

I think the way most people will want to proceed is:

Switch to PEP 793 module initialization (https://peps.python.org/pep-0793/). This will hopefully be a fairly trivial change for most people.
Switch to using opaque objects and accessing all their type data through PyObject_GetTypeData. This will be a painful change for most people (and especially if they're starting from static types).
Follow the general free-threading C API advice in https://docs.python.org/3/howto/free-threading-extensions.html#container-thread-safety (e.g. avoid borrowed reference, use critical sections once they become available). My personal opinion is that it isn't worth duplicating the advice.
Decide if they want to mark their extension as thread-safe.

But steps 1 and 2 are the main ones and are almost not covered here.

clin1234 · 2026-04-12T16:54:01Z

Based on WIP PR: #148013

picnixz · 2026-04-12T16:57:24Z

I don't understand why we are having this PR when the reference documentation is not merged. Can we revisit this later? I would have expected the PEP's author to write this.

picnixz · 2026-04-13T00:53:22Z

I left it as a draft because I do not think it is time for it to be reviewed. Please wait for the PEP author first.

encukou · 2026-04-13T08:13:37Z

Please don't repeat text from free-threading HOWTO. This document should be about migrating from that to the stable ABI; anything that's relevant to free-threading in general should be explained there (and possibly linked from the new document).

Also don't repeat information from the reference docs. A migration guide should link to the docs, and perhaps point out how/why the new thing is different.

And please see here on how-to guides in general: https://diataxis.fr/how-to-guides/

read-the-docs-community · 2026-05-02T00:16:31Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32725685 | 📁 Comparing 3b401db against main (be9c7cb)

🔍 Preview build

101 files changed · + 3 added · ± 98 modified

+ Added

± Modified

This document provides detailed instructions on how to use the Free Threading Stable ABI in CPython, including guidelines for module initialization, API usage, and thread safety considerations.

Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.

Clarified that direct access to PyObject members is prohibited.

Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Updated documentation to clarify the identification of free-threaded limited API builds in C, including changes to macros and initialization methods.

Updated the documentation to clarify the use of the stable ABI and GIL management in Python extensions, including changes to member access and initialization methods.

Removed sections on API guidelines, critical sections, and thread safety from the documentation.

da-woods · 2026-05-17T11:58:05Z

+The CPython C API exposes the :c:macro:`!Py_LIMITED_API` macro: in the free-threaded stable ABI
+build it's defined to ``1``, and in the regular build it's not defined.


This isn't right.

da-woods · 2026-05-17T11:59:50Z

+- define both :c:macro:`!Py_LIMITED_API` and :c:macro:`!Py_TARGET_ABI3T`, or
+- define only :c:macro:`!Py_LIMITED_API` and:
+
+  - on Windows, define :c:macro:`!Py_GIL_DISABLED`;
+  - on other systems, use the headers of free-threaded build of Python.


I think the idiomatic way is probably just to define Py_TARGET_ABI3T with the version hex that you want to target.

The other ways (involving defining Py_LIMITED_API and maybe using the free-threading headers) are a bit opaque so it's probably better not to recommend them.

da-woods · 2026-05-17T12:02:01Z

+Accessing any member of ``PyObject`` directly is now prohibited, like the non-GIL
+stable ABI. For instance, prefer ``Py_TYPE()`` and ``Py_SET_TYPE()`` over ``ob_type``,


like the non-GIL stable ABI

I think this is the wrong way around and it's "the GIL stable ABI".

I think also that accessing the members is recommended against in the GIL stable ABI and actually impossible in the freethreading stable ABI.

da-woods · 2026-05-17T12:02:31Z

+the GIL disabled; otherwise importing the extension will raise a warning and
+enable the GIL at runtime.
+
+Multi-phase and single-phase initialization is supported to indicate that an extension module


I don't think single-phase initialization is supported

da-woods · 2026-05-17T12:03:02Z

+        PySlot_END
+    };
+
+Furthermore, using ``PyABIInfo_VAR`` and ``Py_mod_abi`` is recommended so that an


required I think

da-woods · 2026-05-17T12:04:12Z

+
+.. _critical-sections:
+
+Replacements:


At least in the C and C++ world the macros are available and encouraged. So I'm not sure "replacements" makes sense.

da-woods · 2026-05-17T12:04:31Z

+|:c:macro:`Py_BEGIN_CRITICAL_SECTION_MUTEX` |``PyCriticalSection_BeginMutex``       |
+|:c:macro:`Py_END_CRITICAL_SECTION`         |``PyCriticalSection_End``              |
+-------------------------------------------+---------------------------------------+
+|:c:macro:`Py_BEGIN_CRITICAL_SECTION2_MUTEX`|``PyCriticalSection2_BeginMutex``      |
+|:c:macro:`Py_END_CRITICAL_SECTION2`        |``PyCriticalSection2_End``             |
+-------------------------------------------+---------------------------------------+


I don't think the mutex versions are exposed at all

da-woods · 2026-05-17T12:06:36Z

+``Py_REFCNT``, ``Py_IncRef()`` and ``Py_DecRef()`` over ``ob_refcnt``, etc.
+
+Similarly, members of ``PyVarObject`` are not visible. If you need any object of such type
+to be passed as a ``PyObject`` parameter to any API function, cast it directly as ``PyObject``.


The big consequence here is not that you can't access the members. It's that you can't define structures like

struct S { PyObject_HEAD // your struct goes here };

and thus have to omit the PyObject_HEAD and set the object size to -size to indicate opaqueness.

You also can't use PyVarObject at all easily right now.

bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Apr 12, 2026

github-project-automation Bot added this to Docs PRs Apr 12, 2026

github-project-automation Bot moved this to Todo in Docs PRs Apr 12, 2026

bedevere-app Bot mentioned this pull request Apr 12, 2026

Implement PEP 803 -- abi3t #146636

Open

9 tasks

da-woods reviewed Apr 12, 2026

View reviewed changes

Comment thread Doc/howto/freethreading-stable-abi.rst

picnixz marked this pull request as draft April 12, 2026 17:03

bedevere-app Bot removed the awaiting review label Apr 12, 2026

clin1234 marked this pull request as ready for review April 12, 2026 17:44

bedevere-app Bot added the awaiting review label Apr 12, 2026

picnixz added the DO-NOT-MERGE label Apr 13, 2026

clin1234 requested a review from da-woods May 7, 2026 19:31

clin1234 marked this pull request as draft May 7, 2026 19:31

bedevere-app Bot removed the awaiting review label May 7, 2026

clin1234 force-pushed the patch-6 branch from a4b1bea to 0bddc53 Compare May 13, 2026 23:50

clin1234 marked this pull request as ready for review May 17, 2026 09:33

bedevere-app Bot added the awaiting review label May 17, 2026

clin1234 added 5 commits May 17, 2026 05:33

Add reference to freethreading-stable-abi-howto

8040796

Add documentation for Free Threading Stable ABI usage

7175e14

This document provides detailed instructions on how to use the Free Threading Stable ABI in CPython, including guidelines for module initialization, API usage, and thread safety considerations.

Update documentation on PyObject opaqueness and module init

e0f3bd2

Clarified access restrictions on PyObject members and recommended functions for type and reference count manipulation.

Fix formatting for PyObject opaqueness section

3739aec

Fix formatting of code snippet in documentation

c235a75

clin1234 and others added 9 commits May 17, 2026 05:33

Update documentation on PyObject opaqueness

753156b

Clarified that direct access to PyObject members is prohibited.

Py_Type

344105e

Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Clarify free-threaded limited API build documentation

29b932d

Updated documentation to clarify the identification of free-threaded limited API builds in C, including changes to macros and initialization methods.

Revise freethreading-stable-abi.rst for clarity

8545eeb

Updated the documentation to clarify the use of the stable ABI and GIL management in Python extensions, including changes to member access and initialization methods.

Add freethreading-stable-abi.rst to documentation index

2a11368

Simplify threading and API guidelines in documentation

2f2e756

Removed sections on API guidelines, critical sections, and thread safety from the documentation.

Update freethreading-stable-abi.rst

5d23810

Update freethreading-stable-abi.rst

a8294fa

Update freethreading-stable-abi.rst

43538cf

clin1234 force-pushed the patch-6 branch from 0bddc53 to 43538cf Compare May 17, 2026 09:33

Update module slot definitions to use PySlot from PEP 820

ed0e4fe

da-woods reviewed May 17, 2026

View reviewed changes

clin1234 added 3 commits May 17, 2026 11:22

Update freethreading-stable-abi.rst

a7fcbcc

Fix typo in freethreading-stable-abi.rst

ccdedb0

Update freethreading-stable-abi.rst

3b401db

		The CPython C API exposes the :c:macro:`!Py_LIMITED_API` macro: in the free-threaded stable ABI
		build it's defined to ``1``, and in the regular build it's not defined.

		Accessing any member of ``PyObject`` directly is now prohibited, like the non-GIL
		stable ABI. For instance, prefer ``Py_TYPE()`` and ``Py_SET_TYPE()`` over ``ob_type``,


		.. _critical-sections:

		Replacements:

Uh oh!

Conversation

clin1234 commented Apr 12, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

da-woods left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

da-woods commented Apr 12, 2026

Uh oh!

Uh oh!

clin1234 commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz commented Apr 12, 2026

Uh oh!

picnixz commented Apr 13, 2026

Uh oh!

encukou commented Apr 13, 2026

Uh oh!

read-the-docs-community Bot commented May 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clin1234 commented Apr 12, 2026 •

edited by github-actions Bot

Loading

clin1234 commented Apr 12, 2026 •

edited

Loading

read-the-docs-community Bot commented May 2, 2026 •

edited

Loading